// LexicalHandler.java - optional handler for lexical parse events.
// http://www.saxproject.org
// Public Domain: no warranty.
// $Id: LexicalHandler.java,v 1.5 2002/01/30 21:00:44 dbrownell Exp $

package org.xml.sax.ext;

import org.xml.sax.SAXException;

/**
 * 用于词汇事件的SAX2扩展处理程序。
 *这是SAX2的可选扩展处理程序，用于提供有关XML文档的词汇信息，如注释和CDATA节边界。
 *
 *XML读取器不需要识别该处理程序，它不是核心SAX2发行版的一部分。
 *
 * 词汇处理程序中的事件适用于整个文档，而不仅仅是文档元素，
 * 所有的词法处理程序事件都必须出现在内容处理程序的开始文档和结束文档事件之间。
 *
 * 要为XML阅读器设置词法处理程序，请使用{@link org.xml.sax.XMLReader#setProperty setProperty}方法.
 * 当您尝试注册处理程序,如果读者不报告词汇事件，则会抛出一个{@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}。
 *
 * @since SAX 2.0 (extensions 1.0)
 * @author David Megginson
 * @version 2.0.1 (sax2r2)
 */
public interface LexicalHandler
{

    /**
     * 报告DTD声明的开始（如果有的话）
     *
     * 此方法旨在报告DOCTYPE声明的开始; 如果文档没有DOCTYPE声明，则不会调用此方法。
     *
     * 所有申报通过
     * {@link org.xml.sax.DTDHandler DTDHandler}
     * {@link org.xml.sax.ext.DeclHandler DeclHandler} ,
     * 并且通报事件必须在 {@link #startDTD startDTD} 与{@link #endDTD endDTD} 之间。
     *
     * 来自DTD的注释和处理指令也应按照（逻辑）出现的原始顺序在开始DTD和结束DTD事件之间进行报告;
     * 但是它们不需要出现在相对于DTDHandler或Decl Handler事件的正确位置。
     *
     *
     * 请注意，开始/结束DTD事件将出现在内容处理程序的开始/结束文档事件内以及第一次{@link org.xml.sax.ContentHandler#startElement startElement}事件之前
     *
     * @param name 文档类型名称。
     * @param publicId  外部DTD子集声明的公共标识符，如果没有声明，则返回null
     * @param systemId 外部DTD子集声明的系统标识符，如果没有声明，则为null（请注意，这不是针对文档基础URI解析的）。
     * @exception SAXException 应用程序可能会引发异常。
     * @see #endDTD
     * @see #startEntity
     */
    public abstract void startDTD (String name, String publicId,
                   String systemId)
    throws SAXException;


    /**
     * 报告DTD声明的结束, 如果文档没有DOCTYPE声明，则不会调用此方法。
     * @exception SAXException The application may raise an exception.
     * @see #startDTD
     */
    public abstract void endDTD ()
    throws SAXException;


    /**
     * 报告一些内部和外部XML实体的开始。
     *
     * 参数实体（包括外部DTD子集）的报告是可选的，报告词法处理程序事件的SAX2驱动程序可能不会实现它; 你可以使用
     * http://xml.org/sax/features/lexical-handler/parameter-entities
     * 功能来查询或控制参数实体的报告。
     *
     * 一般实体与定期报告名称,参数实体有“%”返回他们的名字,和外部DTD子集pseudo-entity名称“(DTD)”。
     *
     * 当SAX2驱动程序提供这些事件时，所有其他事件必须正确地嵌套在开始/结束实体事件中。
     *
     * 请注意，跳过的实体将通过{@link org.xml.sax.ContentHandler#skippedEntity skippedEntity}事件,
     * 这是Content Handler界面的一部分
     *
     * 由于SAX使用的流式事件模型，在任何情况下都不能报告一些实体边界：
     * <ul>
     * <li>属性值中的一般实体</li>
     * <li>声明中的参数实体</li>
     * </ul>
     *
     * 这些将被默默扩大，没有迹象表明原来的实体边界在哪里。
     *
     * 还要注意的是，字符引用的边界（实际上不是真正的实体）不会被报告。
     *
     * 所有开始/结束实体事件必须正确嵌套。
     * @param name 实体的名称。 如果是参数实体，名称将以'％'开始，如果是外部DTD子集，则为“[dtd]”。
     * @exception SAXException 应用程序可能会引发异常。
     * @see #endEntity
     * @see org.xml.sax.ext.DeclHandler#internalEntityDecl
     * @see org.xml.sax.ext.DeclHandler#externalEntityDecl
     */
    public abstract void startEntity (String name)
    throws SAXException;


    /**
     * 报告实体的结束。
     * @param name 正在结束的实体的名称。
     * @exception SAXException 应用程序可能会引发异常
     * @see #startEntity
     */
    public abstract void endEntity (String name)
    throws SAXException;


    /**
     * 报告CDATA部分的开始。
     * CDATA部分的内容将通过常规的{@link org.xml.sax.ContentHandler#characters characters} 事件; 此事件仅用于报告边界
     * @exception SAXException 应用程序可能会引发异常
     * @see #endCDATA
     */
    public abstract void startCDATA ()
    throws SAXException;


    /**
     * 报告CDATA部分的结尾。
     * @exception SAXException 应用程序可能会引发异常。
     * @see #startCDATA
     */
    public abstract void endCDATA ()
    throws SAXException;


    /**
     * 在文档的任何位置报告XML注释。
     *
     * 此回调将用于文档元素内部或外部的注释，包括外部DTD子集中的注释（如果已读）。
     * DTD中的注释必须正确嵌套在开始/结束DTD和开始/结束实体事件（如果使用）中。
     * @param ch 在注释中包含字符的数组。
     * @param start 数组中的起始位置。
     * @param length 从数组中使用的字符数。
     * @exception SAXException 应用程序可能会引发异常。
     */
    public abstract void comment (char ch[], int start, int length)
    throws SAXException;
}